Michael Heathman
May 1975


	JSYS instructions added to Tenex by SUMEX & IMSSS.

Maintenance:  SUMEX Systems staff.



This file is arranged to form inserts into the standard
JSYS manual.  To that end, the suggested page number is
given on top of each page;  therefore, best to list without
page numbering.

			CONTENTS
			--------

JSYS	NUM	PAGE	DESCRIPTION
----	---	----	-----------

PSTIN	611	2	String input with editing 
VKEEP	674	7	Set file version retention parameter
PRGE	675	8	Delete and expunge an individual file
ASNSQ	752	9	Assign special network queue slot
RELSQ	753	10	Release special network queue slot
SNDIM	750	11	Send special network message
RCVIM	751	12	Receive special network message
RAND	612	13	Get random number
PTINF	614	14	Put 40(8) word block into special buffer
GTINF	615	15	Read back block from special buffer
TYMLI	653	16	Get TYMNET login information
CNTSZ	607	17	Count number of forks, total size
GTBLT	634	18	BLT SYSTAB table into user space
SIBF	364	19	Skip if input buffer full
DELCH	625	20	Delete character on display
ASPTY	360	21	Assign Pseudo-tty
REPTY	361	22	Release Pseudo-tty
PSTI	362	23	Pseudo-tty Simulate Terminal Input
PSTO	363	24	Pseudo-tty Simulate Terminal Output
SRUBA	365	25	Set special Rubout Action 
STCHA	633	26	Set Terminal Stop character
IIT	630	27	Init PSI with timed delay
SJPCT	626	28	Set job runtime percentage
RJPCT	627	29	Read job runtime percentage
    Section 2					Page 46.1


		    PSTIN	JSYS 611

String input from the teletype, with editing provided.

SHORT FORM CALL (simple line input):

ACCEPTS IN 1:	Tenex string descriptor
			(locates beginning of buffer)
	   2:	Maximum number of bytes to input.

	   3:	Bits 0-8:    Zero for short call.
		Bits 18-26:  Optional additional character	
				to terminate string.
		Bits 27-35:  Optional additional character
				to terminate string.


			PSTIN

RETURNS  + 1:	Always, with an updated string pointer in 1,
		remaining buffer room in 2.

	1 is left in the standard Tenex convention: 
LDB AC, 1  will fetch the terminating character;
DPB AC, 1  will clobber the terminator (as with a null);
IDPB AC, 1 will continue the string.


	PSTIN accepts a line of input from the teletype.  The
line is terminated by RETURN, ALT-MODE, any control-character
other than TAB or LINEFEED, or either of the special terminators
given in the right half of 3.
	Note:  A RETURN is echoed as both RETURN and LINEFEED,
but only RETURN is placed in the buffer.
    Section 2					Page 46.2


	Various editing funtions are provided by the system
during typein:
    ↑X		Prints  ##  and goes to next line;
		 erases everything (start over).

   RUBOUT	Erases one character.  If nothing is left, 
		 same as ↑X.
   
    ↑A		Same as RUBOUT.

    ↑W		Erases one word, where a word is delimited
		 by space and/or TAB and/or LINEFEED.  Erases 
		 spaces or tabs	back to last word if necessary.
		 If nothing left, same as ↑X.

    ↑R		Retype.  Prints  ##, goes to next line, and
		 prints out everything it has so far.

   LINEFEED	Line continuation.  Echoes as carriage-return
		 line-feed, but does not terminate the input.
		 May be erased with RUBOUT or ↑W.  It is 
		 suggested that programs interpret LINEFEED
		 as synonymous with space.

Disposition of erasure: 
	On an imlac (or TEC), the action of RUBOUT and ↑W 
will be to actually erase the appropriate characters from 
the screen.  (This will not work correctly if a tab is erased).
	On a teletype, RUBOUT echoes the erased characters
inside of square brackets.  Thus, for the first erasure, RUBOUT
prints  [  and then the character being erased.  Subsequent
RUBOUT's only echo the character.  When a new input character
is typed, a  ]  is printed prior to echoing the character.
	On a teletype, ↑W causes the system to print ←← 
(two underlines and a space).  Another ↑W does the same thing.
The space following the underlines is to emphasize that the
spaces preceeding the erased word are still present in the
buffer.
	On any device, erasing a LINEFEED will be indicated
by the printing of  ↑↑ .
    Section 2					Page 46.3


	Several other features are supported by PSTIN, in
the hopes of providing the features needed for various
implementations.

LONG FORM CALL:	


ACCEPTS in 1:	Tenex string descriptor 
			(locates beginning of buffer)
	   2:	Maximum number of bytes to input

	   3:	Bit 0 = 1:  Indicates a special character
				table has been provided.
		Bit 1 = 1:  Indicates that a erasure message
				has been provided.
		Bit 2 = 1:  Indicates that characters are
				already in the buffer and
				should be skipped on startup.

		Bits 18-26: Optional additional character
				to terminate input.
		Bits 27-35: Optional additional character
				to terminate input.

	    
	   4:	lh	Number of characters to skip on
			 startup (if B2 of 3 is set).
		rh	Address of special character table
			 (if B0 of 3 is set).
	   5:	Tenex string descriptor for string to print
		 	following ↑X or ↑R  (basically for
			retype of prompt character).


			PSTIN
		
RETURNS  + 1:	Always, with updated string pointer in 1,
		remaining buffer room in 2.


  see next page for more detail on the special features.
    Section 2					Page 46.4


Special features available in long call:
  SKIPPING CHARACTERS ON STARTUP:
	The string descriptor in 1 locates the beginning of 
the buffer.  However, the situation may arise in which the user 
types part of a line and causes termination of the PSTIN without 
really completing what he has to type;  the program can then 
re-enter the PSTIN with the same buffer (now containing the 
partial input) and instruct PSTIN to skip the characters 
already seen.  Input processing continues as if the first 
portion of the bufferhad just been typed;  that part may be 
erased, retyped, etc.

  STRING POINTER IN 5:  
This string will be printed at the beginning of the new line 
following the ↑X editing action.  Similarly, when ↑R is used, 
this string will be printed at the front of the line before 
the input is retyped.

    Section 2					Page 46.5


  SPECIAL CHARACTER TABLE:
This provides a facility to alter the editing character 
assignments, and also provides afacility for arbitrary character 
translation during the PSTIN.  The table has 200(8) entries, one 
per character.  Each entry is 9 bits long, so they are packed 
4 to a word.
Byte format:
  400 bit on:   Special editing action.  Rest of byte is
		coded with the function, as follows:
		  0   ignore		[null]
		  1   erase character	[RUBOUT]
		  2   erase word	[ ↑W ]
		  3   erase all		[ ↑X ]
		  4   retype		[ ↑R ]
	 	  5   continue line	[LINEFEED]
			(echo CRLF; character passed to program)	
	The characters for functions 0 thru 4 are not	
	put into the buffer.

   400 bit off:  The low-order 7 bits specify the character
	to be echoed and placed in the buffer.  This may or
	may not correspond with the character typed.  A
	suggested use would be to force upper case translation,
	though any mapping is possible.

   200 bit on:  Character is a terminator.  It is translated as
	just described, and placed in the buffer, and then the
	PSTIN is terminated.

If the user does not supply a special character table, the
system will use a default table giving the editing functions
and terminators described above.

    Section 2					Page 66.1


		VKEEP 		JSYS	674 

Version KEEP parameter.  Sets number of versions to be kept for a 
specified file, and disposal of extra versions.


ACCEPTS IN 1:	JFN of highest version number of file
	   2:	B30 0 => delete and expunge extra versions
		    1 => delete extra versions
		B31-B35 number of versions to keep


			VKEEP 

RETURNS  + 1:	Unsuccessful, errors in 1
	   2:	Successful, keep parameter set for all versions of this
		file.


Excess versions caused by lowering the number of versions to keep will
be removed on the next CLOSF of any version of the file.


VKEEP errors:
	illegal file designator
	illegal access
    Section 2					Page 66.2


		PRGE 		JSYS	675 

PuRGE a file.  Deletes and expunges a single file without affecting other
expunge sensitive files (;T's, etc.)


ACCEPTS IN 1:	JFN of file


			PRGE 

RETURNS  + 1:	Unsuccessful, errors in 1
	   2:	Successful, the file is deleted and expunged, and the
		JFN is released.


PRGE errors:
	Illegal file designator
	Illegal access
    Section 2					Page 90.1


		ASNSQ 		JSYS	752 

ASsigN Special Queue number.  Assigns a special queue number for the
manipulation of special messages outside the standard Host-to-Host
(and higher) protocols.  Special Que messages are manipulated with
the SNDIM and RCVIM jsys's.


ACCEPTS IN 1:	mask
	   2:	value


			ASNSQ 

RETURNS  + 1:	Unsuccessful, error bits in 1
	   2:	Successful, special queue number returned in RH (1)


A special queue number is assigned only if an unassigned special 
queue slot is available, and the commonly masked bits of value in
this application and any other assigned special queue slot are not equal.
WHEEL or NETWIZARD capability is necessary.


ASNSQ errors:
NTWZX1:	Net Wizard capability not enabled.
ASNSX1:	No special queue numbers available.
ASNSX2:	Special queue mask/value conflict
    Section 2					Page 90.2


		RELSQ 		JSYS	753 

RELease Special Queue number.  


ACCEPTS IN 1:	Special queue number, or -1 for all special queue
		numbers assigned to this job


			RELSQ 

RETURNS  + 1:	Always.  Specified special queue numbers released.


RELSQ errors:
	none

    Section 2					Page 90.3


		SNDIM 		JSYS	750 

SeND special (Imp) Message.  Allows the transmission of network messages
outside the Host-to-Host (and higher) protocols.


ACCEPTS IN 1:	Special Queue number
	   2:	Address of message buffer in user virtual core


			SNDIM 

RETURNS  + 1:	Unsuccessful, error number in 1
	   2:	Successful, special network message sent


SNDIM errors:
SQX1:	Illegal special queue number
SQX2:	Special queue number not assigned this job
SNDIX1:	Illegal message size
SNDIX2:	No Imp buffer space
SNDIX3:	Message with NCP link number is illegal
SNDIX4:	Illegal message header
SNDIX5:	IMP down
    Section 2					Page 90.4


		RCVIM 		JSYS	751 

ReCeiVe special network (Imp) Message.  Allows the reception of special
messages outside the standard Host-to-Host (and higher) protocols.


ACCEPTS IN 1:	Special Queue number
	   2:	Address of message buffer in users virtual core


			RCVIM 

RETURNS  + 1:	Unsuccessful, error number in 1.
	   2:	Successful, special message received.


RCVIM errors:
SQX1:	Illegal special queue number
SQX2:	Special queue number not assigned this job
    Section 3					Page 4.1


		    RAND	JSYS 612

Returns a floating point random number between 0 and 1. 


ACCEPTS:	no arguments


			    RAND

RETURNS  + 1:	always, with a random number in BOTH 1 and 2.

		(** the same number in 2 as in 1 **)


Comments:
	The algorithm is borrowed from a JACM article, and
claims to have been tested and to give a good distribution.
RAND is a fast jsys, which means it is every bit as efficient
as having the code in your own program.  The only disadvantage
is that you have no control over the seed  (but then random
numbers are supposed to be random, aren't they?).  (David Levine).

    Section 3					Page 4.2


		    PTINF	JSYS  614

A JSYS to pass a 40-word block of data from one program to
another. without need for specific address conventions, shared
pages, etc.  The data is stored in system memory, and may be
read by the companion JSYS GTINF.

The PTINF-GTINF pair was created by IMSSS for use by the student
instructional system, and is retained at SUMEX for compatibility.
The buffer area is available, however, for any inter-program 
communication use.


ACCEPTS IN 1:	-1 to specify the current job, otherwise a	
		job number (priviledged operation).
	   2:	Starting address of 40-word block of user memory


			PTINF

RETURNS  + 1:	Error.
	 + 2:	If successful, with data in block transferred
		into a buffer in system memory.



PTINF Errors:
	"Wheel" special priviledges needed to access the buffer
		belonging to another job.  (AC 1 does not 
		contain -1).
	Illegal data address.


    Section 3					Page 4.3


		    GTINF	JSYS  615

To read information previously stored by PTINF.


ACCEPTS IN 1:	-1 to specify current job, or job number.	
	   2:	Starting address of 40-word block of user memory.
		

			GTINF

RETURNS  + 1:	On error.
	 + 2:	If successful, with information stored in
		system "inf" buffer transferred into the block
		specified by AC2.


GTINF Errors:
	"Wheel" special priviledges needed to access the
		buffer belonging to another job.
	Illegal address for data area.
    Section 3					Page 4.4

			TYMLI		JSYS 653

Gets TYMnet Login Information for TYMNET lines only.  Information returned
includes initial terminal type (in TYMNET terminal code), originating node
and port.

ACCEPTS IN 1:	TTY designator

	
			TYMLI

RETURNS  + 1:	Always. TYMNET login information in 1, or -1 for non
		TYMNET line.
	
		TYMNET login information of format:
		B9-B16 TYMNET tty type (see TYMSRV for code equivalents)
		B17-B23 Port number on originating node
		B24-B35 Originating node number


TYMLI errors:
	none
    Section 3					Page 8.1


		CNTSZ		JSYS	607

Counts size of job, in number of forks and size of balance
set.  The latter is the job size considered by the Tenex
scheduler, and is intended to reflect the current memory
demands of the job.


ACCEPTS IN 1:	A Tenex job number.


			CNTSZ

RETURNS  + 1:	Always, with data in 2:
		 LH - Number of forks for the job.
		 RH - Number of pages in the balance set 
			assigned to the job.


    Section 3					Page 14.1


		GTBLT 		JSYS	634 

GeT systab tables with BLT.  BLT's a table listed in SYSTAB into users
virtual core. (See SWPMON for current list of tables)


ACCEPTS IN LH (1):  Starting index or -1 for entire table
	   RH (1):  Table number
	   LH (2):  Number of entries to move
	   RH (2):  Buffer address in user space


			GTBLT 

RETURNS  + 1:	Unsuccessful, error number in 1
	   2:	Successful, SYSTAB table copied into user space


User must have GETAB capability

GTBLT errors:
	Illegal table number
	Illegal table index
    Section 4					Page 20.1


		SIBF 		JSYS	364 

Skip If input Buffer Full.


ACCEPTS IN 1:	TTY designator


			SIBF 

RETURNS  + 1:	Input buffer not full, number of chars in buffer
		in 2.
	   2:	Input buffer full.


SIBF errors:
	Illegal TTY designator
    Section 4					Page 22.1


		    DELCH	JSYS 625

To delete character on display terminal.  Current display terminals
are the IMLAC, TEC, and DATAMEDIA.


ACCEPTS IN 1:	a TENEX destination designator


			DELCH

RETURNS  + 1:	unsuccessful, destination not a terminal

	 + 2:	terminal is display, but line character count is 0

	 + 3:	terminal is display, one character position has been
		deleted

	 + 4:	non-display terminal, no action has been taken


Comment:
	This JSYS determines the terminal type by reading the terminal
type word that is read and set with the GTTYP/STTYP JSYS's.

    Section 4					Page 32.1


		ASPTY 		JSYS	360 


ASsign Pseudo-TtY (PTY) line to this job.


			ASPTY 

RETURNS  + 1:	Unsuccessful, no PTY assigned
	   2:	Successful, PTY designator (of form 400000+n) in 1


ASPTY errors:
	none
    Section 4					Page 32.2


		REPTY 		JSYS	361 

RElease Pseudo-TtY (PTY) line.


ACCEPTS IN 1:	PTY designator to release, -1 to release all PTY's owned
		by this job.
			

			REPTY 

RETURNS  + 1:	Unsuccessful, error in 1
	   2:	Successful, PTY (or all of job's PTYs) released


REPTY errors:
	illegal PTY designator
    Section 4					Page 32.3


		PSTI 		JSYS	362 

Pseudo-tty Simulate Tty Input function; insert character into 
pseudo-tty input buffer.


ACCEPTS IN 1:	PTY designator
	   2:	character


			PSTI 

RETURNS  + 1:	Unsuccessful, error if error number in 1
		else input buffer full
	   2:	Successful, character inserted


PSTI errors:
	illegal PTY line designator
    Section 4					Page 32.4


		PSTO 		JSYS	363 

Pseudo-tty Simulate Tty Output function; retrieves character 
from pseudo-tty output buffer.


ACCEPTS IN 1:	PTY line designator
	   2:	0 => on empty output buffer, take error return
		-1 => on empty output buffer, block until 
			not empty and then return char, 
		      or 
			PTY process blocks for input and then take error
	 		return


			PSTO 

RETURNS  + 1:	Unsuccessful, error if error number in 1, else output
		buffer empty
	   2:	Successful, char in 2


PSTO errors:
	Illegal PTY designator
    Section 4					Page 32.5


		SRUBA 		JSYS	365 

Set RUBout special handling Action word for controlling tty.


ACCEPTS IN 1:	B29-35: substitute rubout character


			SRUBA 

RETURNS  + 1:	Always


Whenever the substitute rubout char is sent, the job will see a rubout.


SRUBA errors:
	none
    Section 4					Page 32.6


		STCHA 		JSYS	633 


Sets STop CHAracter for controlling tty


ACCEPTS IN 1:	B29-B35 stop character


			STCHA 

RETURNS  + 1:	Always


Output to the controlling tty will stop immediately upon receipt of the
current stop char, and will resume again upon receipt of any character,
including the stop char. (In other words, the stop char will act like 
a toggle switch)  ↑C may not be used as the stop character.


STCHA errors:
	none
    Section 5					Page 16.1


		    IIT		JSYS 630

Initiate delayed pseudo-interupt on specified channels in a fork.  This
is like the IIC JSYS with the delay timing added.


ACCEPTS IN 1:	a fork handle

	   2:	a 36-bit word, b0 for channel 0, b1 for channel 1, etc.

	   3:	milliseconds to wait to initiate interupt


			IIT

RETURNS  + 1:	always


There is no promise of other than gross accuracy for the timing of this
JSYS.  It is subject to the vagaries of the scheduler and will not be
accurate within milliseconds.
    Section 6					Page 22.1


		SJPCT 		JSYS	626 


Set Job PerCenTage. Sets reservation scheduler job percentage.  Any job
that runs more than its percentage of CPU time in a given interval (see
I4.MAC for current interval) will, generally, not be run again in that
interval while there are still jobs which have not gotten their percentage
of CPU time.


ACCEPTS IN 1:	TSS job number or 0 or -1 for current job
	   2:	Maximum percentage,,current percentage


			SJPCT 

RETURNS  + 1:	Always


If the maximum percentage (LH(2)) is zero or illegal (greater than 100%),
then the last set maximum percentage is used.  If the current percentage
is zero or greater than the maximum percentage, the maximum percentage is
used. The maximum percentage is the highest percentage any SJPCT call with
LH(2) equal to zero can set.  Maximum percentage or either percentage for
any other job may only be set with by WHEELs.  This enable WHEELS to set
maximum percentages within which other jobs may set their own current 
percentages


SJPCT errors:
	none
    Section 6					Page 22.2


		RJPCT 		JSYS	627 

Read Job PerCenTage.  Reads job percentage parameters set with SJPCT.


ACCEPTS IN 1:	TSS job number or 0 or -1 for current job


			RJPCT 

RETURNS  + 1:	Always, with 
	      1: maximum percentage,,current percentage
	      2: remaining job quantum, this interval


RJPCT errors:
	none